Skip to content

Add parameterized Qiskit LUCJ ansatz#669

Open
MarcoBarroca wants to merge 1 commit into
qiskit-community:mainfrom
MarcoBarroca:lucj-parameterized-qiskit
Open

Add parameterized Qiskit LUCJ ansatz#669
MarcoBarroca wants to merge 1 commit into
qiskit-community:mainfrom
MarcoBarroca:lucj-parameterized-qiskit

Conversation

@MarcoBarroca

Copy link
Copy Markdown

Summary

This adds a native Qiskit parameterized implementation of the spin-balanced LUCJ ansatz.

I had an internal prototype for this path, and spent time converting it into a proper ffsim PR: public helpers, input validation, tests, and a docs example, rather than just adding the prototype directly.

The main entry point is ffsim.qiskit.lucj_spin_balanced_ansatz, which builds the merged LUCJ circuit form used after ffsim.qiskit.PRE_INIT. The circuit exposes Qiskit parameters directly on the orbital-rotation and diagonal Coulomb gates, so it can be optimized in standard Qiskit workflows.

Closes #411.

Details

  • Adds ffsim.qiskit.lucj_spin_balanced_ansatz.
  • Adds lucj_spin_balanced_parameters for initializing the parameterized circuit from an existing spin-balanced UCJ operator.
  • Adds lucj_spin_balanced_parameters_from_t2 for initializing from CCSD amplitudes.
  • Supports restricted same-spin and opposite-spin interaction_pairs.
  • Documents the Qiskit workflow in the LUCJ how-to guide.
  • Tests equivalence against the existing UCJ-to-Qiskit path, including restricted interactions and t2 initialization.

Validation

Locally I ran:

  • ruff check python/ffsim/qiskit/__init__.py python/ffsim/qiskit/lucj.py tests/python/qiskit/lucj_test.py
  • ruff format --check python/ffsim/qiskit/__init__.py python/ffsim/qiskit/lucj.py tests/python/qiskit/lucj_test.py
  • ruff check docs/how-to-guides/qiskit-lucj.ipynb
  • pytest tests/python/qiskit/lucj_test.py
  • pytest tests/python/qiskit/gates/ucj_test.py tests/python/variational/ucj_spin_balanced_test.py
  • pytest tests/python/qiskit

@CLAassistant

CLAassistant commented Jun 12, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@MarcoBarroca

Copy link
Copy Markdown
Author

I’m going to keep this as a draft for now while I do a deeper local validation pass.

In addition to the committed tests, I want to check a few things more exhaustively before marking this ready for review:

  • random spin-balanced UCJ operators against the existing UCJOpSpinBalancedJW -> PRE_INIT -> decompose path
  • random state evolution checks, including fixed particle-number sectors
  • restricted interaction_pairs cases for both same-spin and opposite-spin interactions
  • t2-based initialization across zero, dense, sparse, padded, and multi-repetition inputs
  • parameter ordering and binding behavior on the generated Qiskit circuit
  • validation behavior for bad inputs and duplicate/lower-triangular interaction pairs

The main thing I want to be sure of is that the new parameterized circuit is not just structurally reasonable, but actually matches the existing ffsim/Qiskit LUCJ behavior across representative cases. Once that internal pass looks clean, I’ll move this out of draft.

@MarcoBarroca

Copy link
Copy Markdown
Author

I did the extra local validation I wanted to do before marking this ready.

Besides the tests in the PR, I ran randomized checks against the existing ffsim/Qiskit LUCJ path. That included full-state evolution, fixed particle-number sectors, restricted interaction pairs, and t2-based initialization cases. I also checked parameter ordering, parameter binding, and a few invalid-input paths.

Everything matched to numerical precision. The generated parameterized circuits agreed with the existing merged UCJ circuit behavior up to global phase, including the restricted-interaction cases.

Marking this ready for review now.

@MarcoBarroca MarcoBarroca marked this pull request as ready for review June 12, 2026 13:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add LUCJ ansatz as parameterized Qiskit circuit

2 participants